---
title: 部署你的 Astro 站点至 Cloudflare Pages
description: 如何使用 Cloudflare Pages 将你的 Astro 网站部署到网络上。
type: deploy
i18nReady: true
---
import ReadMore from '~/components/ReadMore.astro'

你可以将你的 Astro 项目部署在 [Cloudflare Pages](https://pages.cloudflare.com/) 上。Cloudflare Pages 是一个供前端开发人员协作和部署静态 (JAMstack) 或 SSR 网站的平台。

本指南包含：

- [如何使用 Git 部署一个站点](#如何使用-git-部署一个站点)
- [如何使用 Wrangler 部署一个站点](#如何使用-wrangler-部署一个站点)
- [如何部署 SSR 站点](#如何部署-ssr-站点)

## 前提条件

开始之前，你需要：

- 一个 Cloudflare 账号。如果你暂时还没有，你可以现在免费去 Cloudflare 官网注册一个。
- 你的源代码存储在一个 [GitHub](https://github.com/) 或者 [GitLab](https://about.gitlab.com/) 仓库里。

## 如何使用 Git 部署一个站点

1. 在 Cloudflare Pages 设置一个新项目。
2. 将你的代码提交到一个 Git 仓库中 (GitHub, GitLab)。
3. 登陆 Cloudflare Dashboard 并在 **Account Home** > **Pages** 选择你的账号。
4. 选择 **Create a new Project**（创建一个新项目）和 **Connect Git**（连接 Git）选项。
5. 选择你想部署的 Git 项目并点击 **Begin setup**（初始设置）。
6. 使用以下的构建设置：

    - **Framework preset（框架预设）:** `Astro`
    - **Build command（构建命令）:** `npm run build`
    - **Build output directory（构建输出目录）:** `dist`

7. 点击 **Save and Deploy**（保存并部署）按钮。

## 如何使用 Wrangler 部署一个站点

1. 安装 [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/get-started/)。
2. 使用 `wrangler login` 在 Wrangler 登陆 Cloudflare 账号并授权。
3. 运行你的构建命令（比如 `npm run build`）。
4. 使用 `npx wrangler pages deploy dist` 进行部署。

```bash
# 安装 Wrangler CLI（命令行）
npm install -g wrangler
# 在 CLI 中登陆 Cloudflare 账号
wrangler login
# 运行你的构建命令
npm run build
# 创建新的部署
npx wrangler pages deploy dist
```

上传完所有的文件后，Wrangler 将为你提供一个预览 URL 以检查你的站点。当你登录 Cloudflare Pages 仪表板时，你将看到你的新项目。

### 使用 Wrangler 在本地启用预览

要使预览版正常工作，你必须安装 `wrangler`

```bash
pnpm add wrangler --save-dev
```

然后就可以将预览脚本从 Astro 的内置预览命令更新为 `wrangler` 了：

```json title="package.json"
"preview": "wrangler pages dev ./dist"
```

## 如何部署 SSR 站点

你可以使用 [`@astrojs/cloudflare` 适配器](/zh-cn/guides/integrations-guide/cloudflare/)将 Astro SSR 站点部署到 Cloudflare Pages。

请按照以下步骤设置适配器。完成后，你可以使用上述文档中的任何方法进行部署。

### 快速安装

使用以下 `astro add` 命令添加 Cloudflare 适配器以在你的 Astro 项目中启用 SSR。这将安装适配器并一步对你的文件 `astro.config.mjs` 进行适当的更改。

```bash
npx astro add cloudflare
```

### 手动安装

如果你想要手动安装适配器，请完成以下两个步骤：

1. 使用你喜欢的包管理器将 `@astrojs/cloudflare` 添加到项目的依赖项中。如果你正在使用 npm 或不确定是哪个包管理器，请在终端中运行：

    ```bash
    npm install @astrojs/cloudflare
    ```

2. 将以下内容添加到你的 `astro.config.mjs` 文件中：

    ```js title="astro.config.mjs" ins={2, 5-6}
    import { defineConfig } from 'astro/config';
    import cloudflare from '@astrojs/cloudflare';

    export default defineConfig({
      output: 'server',
      adapter: cloudflare()
    });
    ```

<ReadMore>阅读更多关于 [Astro 中的 SSR（服务端渲染）](/zh-cn/guides/server-side-rendering/) 的信息。</ReadMore>

## 故障排除

### 客户端 hydration

由于 Cloudflare 的 Auto Minify（自动压缩）功能，客户端 Hydration 可能会失败。如果你在控制台中看到 `Hydration completed but contains mismatches`，请确保在 Cloudflare 设置中禁用 Auto Minify。

### Node.js 运行时 API

如果你正在构建一个使用 [Cloudflare 服务端渲染适配器](/zh-cn/guides/integrations-guide/cloudflare/) 的按需渲染项目，并且服务器在构建时失败，出现如 `[Error] Could not resolve "XXXX. The package "XXXX" wasn't found on the file system but is built into node.` 的错误信息：

- 这意味着你在服务器端环境中使用的某个包或导入项与 [Cloudflare 运行时 API](https://developers.cloudflare.com/workers/runtime-apis/nodejs/) 不兼容。

- 如果你直接导入了一个 Node.js 运行时 API，请参考 Astro 关于 Cloudflare 的 [Node.js 兼容性](/zh-cn/guides/integrations-guide/cloudflare/#nodejs-兼容性) 文档，了解如何解决这个问题的进一步步骤。

- 如果你导入的包中包含了 Node.js 运行时 API，请检查该包的作者是否支持 `node:*` 的导入语法。如果不支持，你可能需要找到一个替代的包。
